Add readiness serving contract by dzarlax · Pull Request #177 · Dzarlax-AI/health_dashboard

dzarlax · 2026-06-06T11:18:46Z

Summary

add grouped readiness_serving metadata for freshness, confidence, reason, and component evidence
keep existing readiness_confidence/readiness_cap_reason/readiness_components fields for compatibility
document the contract in README and update MCP readiness tool descriptions
record the approved implementation result in the Implement readiness serving and freshness contract before confidence UI #166 HTML plan

Closes #166

Tests

go test ./internal/health ./internal/storage -run "Test.*Readiness.*Evidence|Test.*Readiness.*Serving|TestComputeBriefing_ExposesReadinessServingContract" -count=1
go test ./internal/ui ./internal/mcpserver -count=1
go test ./internal/health ./internal/storage -count=1
go test ./...
go vet ./...
git diff --check

Summary by CodeRabbit

New Features
- Added readiness serving metadata to health briefing responses with status indicators (fresh, stale, missing, data accruing, low coverage, capped) and confidence levels.
- Readiness data now includes per-component freshness and confidence details.
Documentation
- Updated MCP tool documentation to clarify readiness contract behavior.
- Published readiness serving contract specification.

coderabbitai · 2026-06-06T11:18:57Z

Warning

Review limit reached

@dzarlax, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 15 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d2293ee-3aa4-4171-b8ba-4e867921b418

📥 Commits

Reviewing files that changed from the base of the PR and between 10b879a and a0a82e2.

📒 Files selected for processing (3)

docs/ai-plans/2026-06-06-issue-166-readiness-serving-freshness-contract.html
internal/health/readiness.go
internal/health/readiness_evidence_test.go

📝 Walkthrough

Walkthrough

This PR implements a stable readiness serving and freshness contract by adding a new grouped readiness_serving object to briefing responses. The object exposes status, confidence, reason, and per-component details derived from readiness score, cap reason, and component data freshness, enabling downstream UI and MCP consumers to render confidence states without duplicating backend logic.

Changes

Readiness serving and freshness contract

Layer / File(s)	Summary
Type definitions and status constants `internal/health/types.go`	`ReadinessServingState` struct added with required `status` and `confidence` plus optional `reason` and `components` fields; six status constants defined (fresh/missing/stale/data-accruing/low-coverage/capped); field added to `BriefingResponse` as JSON `readiness_serving`.
Serving state computation logic `internal/health/readiness.go`	`Serving` field added to `readinessComputation`; three new helpers compute and update serving state: `readinessServingState()` maps confidence/cap-reason/freshness to Status enum, `updateReadinessServing()` updates response, `hasComponentFreshness()` checks metric freshness; logic called during both evidence-based and no-evidence computation paths.
Integration into briefing response `internal/health/scoring.go`, `internal/health/headline.go`	`ComputeBriefing` assigns `readiness.Serving` to response and calls `updateReadinessServing(resp)` post-coherence; `applyReadinessResponseCap` also calls `updateReadinessServing(resp)` to sync serving state with capped readiness values.
Test coverage for serving state `internal/health/readiness_evidence_test.go`	Four existing tests extended with assertions verifying serving status transitions (data_accruing, capped, low_coverage); two new tests validate `readinessServingState()` returns correct missing-component status and `ComputeBriefing()` exposes non-nil serving contract with component details.
API and MCP documentation `README.md`, `internal/mcpserver/tools.go`	README adds "Readiness serving contract" section documenting JSON structure, enums, and per-component details; `get_health_briefing` and `get_readiness_history` tool descriptions updated to reference serving contract and clarify freshness/confidence semantics.
Implementation plan documentation `docs/ai-plans/2026-06-06-issue-166-readiness-serving-freshness-contract.html`	Comprehensive plan document tracks issue `#166`: goal, behavior changes, assumptions, implementation steps, risks, test coverage, verification results, known limitations, and approval gate; marks implementation complete as of 2026-06-06.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Dzarlax-AI/health_dashboard#1: Both PRs involve the readiness coherence/capping flow; this PR's updateReadinessServing() calls after applyCoherencePass ensure the new serving contract reflects any stress/sleep-debt coherence caps applied by that PR's logic.

Poem

🐰 A contract unfolds, fresh and clear,
Serving states whisper what scores revere—
No more guessing confidence's way,
Down to the UI, data at play! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'Add readiness serving contract' accurately describes the main objective of the changeset, which introduces a new readiness_serving metadata structure for freshness, confidence, and component evidence.
Description check	✅ Passed	The PR description includes a clear summary section, explicitly closes issue `#166`, provides comprehensive test commands, and addresses all major changes including compatibility concerns.
Linked Issues check	✅ Passed	The PR implementation fully addresses issue `#166` requirements: exposes stable readiness_serving metadata with status/confidence/reason/components, preserves backward compatibility, documents the contract in README and MCP tools, includes comprehensive tests covering fresh/stale/low-coverage/data-accruing cases, and passes test/vet checks.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the readiness serving contract: new types/constants, status logic, test coverage, documentation updates, and MCP tool descriptions. No unrelated modifications to scoring behavior or other systems.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/readiness-serving-contract

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@docs/ai-plans/2026-06-06-issue-166-readiness-serving-freshness-contract.html`:
- Line 22: Update the stale status badge: find the <p class="badge"> element
that currently contains the text "Approval required before implementation" and
replace its content to reflect the document's true state (e.g., "Approved and
implemented" or "Implemented") so the badge matches the later
approval/implementation notes in the document.

In `@internal/health/readiness.go`:
- Around line 377-399: The function readinessServingState currently defaults to
ReadinessServingFresh when no confidence/reason are provided; change it to treat
evidence-free input as missing by checking for empty components (len(components)
== 0) and empty reason and setting status = ReadinessServingMissing in that case
before the other conditionals; update readinessServingState (and keep the
existing hasComponentFreshness checks, ReadinessComponentSummary copying, and
ReadinessServingState construction) so requests coming from the e == nil path
are classified as Missing rather than Fresh.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01f90aa6-4610-4895-8af3-9f0f34f1fb80

📥 Commits

Reviewing files that changed from the base of the PR and between 17c5787 and 10b879a.

📒 Files selected for processing (8)

README.md
docs/ai-plans/2026-06-06-issue-166-readiness-serving-freshness-contract.html
internal/health/headline.go
internal/health/readiness.go
internal/health/readiness_evidence_test.go
internal/health/scoring.go
internal/health/types.go
internal/mcpserver/tools.go

Add readiness serving contract

10b879a

coderabbitai Bot reviewed Jun 6, 2026

View reviewed changes

Comment thread docs/ai-plans/2026-06-06-issue-166-readiness-serving-freshness-contract.html Outdated

Comment thread internal/health/readiness.go

Address readiness serving review feedback

a0a82e2

dzarlax merged commit 70fa00a into main Jun 6, 2026
4 checks passed

dzarlax mentioned this pull request Jun 6, 2026

Design confidence and uncertainty indicators for Health Dashboard scores #157

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add readiness serving contract#177

Add readiness serving contract#177
dzarlax merged 2 commits into
mainfrom
codex/readiness-serving-contract

dzarlax commented Jun 6, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 6, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

dzarlax commented Jun 6, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tests

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dzarlax commented Jun 6, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 6, 2026 •

edited

Loading